Skip to content

Migrate the API naming guidelines into the DocC catalog#74

Open
heckj wants to merge 3 commits intoswiftlang:mainfrom
heckj:api-guidelines
Open

Migrate the API naming guidelines into the DocC catalog#74
heckj wants to merge 3 commits intoswiftlang:mainfrom
heckj:api-guidelines

Conversation

@heckj
Copy link
Copy Markdown
Member

@heckj heckj commented Mar 11, 2026

Summary

This is a fairly direct migration of the API naming guidelines. The first commit is explicitly the content from the swift-org-website Jekyll based markdown, then the following commits break up that code and translate the content over to DocC format. I chose, in particular, to break this up so that each guideline became it's own "article" with a number, using a prefix of "API" for the numbering scheme, so that each one - when published - is extremely easy to reference directly with a constant URI.

This PR hasn't changed any of the content - although I'd recommend making a few basic changes that align better with our general style guidelines that have evolved since this was originally written. In particular, I'd likely remove the bold in the abstracts and remove any latin abbreviations- but I wanted to set it up for review and looking prior to any additional editorial changes for better readability.

Related Issue

Closes: #44

Testing

cd api-guidelines
swift package --disable-sandbox preview-documentation
open http://localhost:8080/documentation/apiguidelines

Build Verification

  • Ran swift package generate-documentation --analyze --warnings-as-errors successfully
  • Previewed documentation locally with swift package --disable-sandbox preview-documentation

Content Review


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@heckj heckj self-assigned this Mar 11, 2026
@heckj heckj requested a review from a team as a code owner March 11, 2026 21:54
@heckj heckj added content migration Content originally housed in the swift.org under /documentation/articles content review Technical review in progress status: in-review Content is under technical review and removed content review Technical review in progress labels Mar 11, 2026
### Naming — Strive for Fluent Usage

- <doc:API-0006>
- <doc:API-0007>
Copy link
Copy Markdown

@xwu xwu Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a striking example of a guideline that doesn't stand on its own as a document due to brevity. There are others that are duals of each other (such as "Include words to avoid ambiguity" and "Omit needless words") which take on a different color if separated.

Have you considered instead separating the guidelines such that each document encompasses one of the headings here (e.g., grouping guidelines 6 through 13) or something of that ilk?

Edit: I'm not sure why the heading says the review is on behalf of the group—this is just me wearing my individual hat and not a comment from the steering group.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GH thing is labelling it as the group since you're a part of that group. No worries, I get you're not explicitly speaking for the whole group.

Yeah, 7 is incredibly short - and if I were doing this from scratch, I'd likely make some explicit choices about pairing things up, but wanted to start with each section from the original as it's own guideline to start the conversation. While it's incredibly short, the content is still focused, even if it's effectively just the abstract of the article with no deeper content inside it.

Copy link
Copy Markdown
Member

@allevato allevato Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this guideline in particular (factory methods), I think having it separated is actually the perfect opportunity to improve it (not in this PR of course, but as part of a future effort).

Without ratholing too much on this specific rule, in my experience I think it's been largely misunderstood. I've reviewed a great amount of Swift code where people interpret "factory method" is just "any method that creates and returns some new value" and sprinkle make all over the place, when (based on my own observations of standard library patterns) I think it's supposed to be interpreted more narrowly like the "factory design pattern" where a method is implemented by multiple concrete types and each can return a different concrete type satisfying a common requirement.

That's the kind of elaboration that we can and should do on each of these rules once the initial changes land, because in the original one-pager form, it would have been far too unwieldy to present that much information. There may be some rules where there really is just nothing to be said, but for the most part I think this split presentation will let us really flesh these out in more detail, improving on an already valuable document.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content migration Content originally housed in the swift.org under /documentation/articles status: in-review Content is under technical review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs migration - API Design Guidelines

3 participants